.TH "General functions" 3 "Fri Apr 15 2016" "Version 0.10.0-146_trunk" "libnetconf" \" -*- nroff -*-
.ad l
.nh
.SH NAME
General functions \- 
.PP
libnetconf's miscellaneous functions\&.  

.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBNC_MSG_TYPE\fP { \fBNC_MSG_UNKNOWN\fP, \fBNC_MSG_WOULDBLOCK\fP, \fBNC_MSG_NONE\fP, \fBNC_MSG_HELLO\fP, \fBNC_MSG_RPC\fP, \fBNC_MSG_REPLY\fP, \fBNC_MSG_NOTIFICATION\fP = -5 }"
.br
.RI "\fIEnumeration of NETCONF message types\&. \fP"
.ti -1c
.RI "enum \fBNC_VERB_LEVEL\fP { \fBNC_VERB_ERROR\fP, \fBNC_VERB_WARNING\fP, \fBNC_VERB_VERBOSE\fP, \fBNC_VERB_DEBUG\fP }"
.br
.RI "\fIVerbosity levels\&. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "void \fBnc_callback_print\fP (void(*func)(\fBNC_VERB_LEVEL\fP level, const char *msg))"
.br
.RI "\fISet a callback function for printing libnetconf's messages\&.
.PP
If the func parameter is NULL, the callback is set back to the default (no) function\&. \fP"
.ti -1c
.RI "int \fBnc_close\fP (void)"
.br
.RI "\fIRelease libnetconf resources\&. Init flag is used to determine if close should be applied as system-wide (NC_INIT_MULTILAYER) or not (NC_INIT_SINGLELAYER)\&. System-wide \fBnc_close()\fP closes all the shared structures if no other libnetconf participant is currently running\&. Local release of the calling instance from the shared structures is done in both cases\&. \fP"
.ti -1c
.RI "time_t \fBnc_datetime2time\fP (const char *datetime)"
.br
.RI "\fITransform given string in RFC 3339 compliant format to the time_t (seconds since the epoch) accepted by most Linux functions\&. \fP"
.ti -1c
.RI "struct nc_err * \fBnc_err_dup\fP (const struct nc_err *error)"
.br
.RI "\fIDuplicate an error description structure\&. \fP"
.ti -1c
.RI "void \fBnc_err_free\fP (struct nc_err *err)"
.br
.RI "\fIFree NETCONF error structure\&. \fP"
.ti -1c
.RI "const char * \fBnc_err_get\fP (const struct nc_err *err, \fBNC_ERR_PARAM\fP param)"
.br
.RI "\fIGet value of the specified parameter of the NETCONF error structure\&. \fP"
.ti -1c
.RI "struct nc_err * \fBnc_err_new\fP (\fBNC_ERR\fP error)"
.br
.RI "\fICreate a new error description structure\&. \fP"
.ti -1c
.RI "int \fBnc_err_set\fP (struct nc_err *err, \fBNC_ERR_PARAM\fP param, const char *value)"
.br
.RI "\fISet selected parameter of the NETCONF error structure to the specified value\&. \fP"
.ti -1c
.RI "void \fBnc_hello_timeout\fP (int timeout)"
.br
.RI "\fISet <hello> timeout - how long libnetconf will wait for the <hello> message from the other side\&. Default value is -1 (infinite timeout)\&. \fP"
.ti -1c
.RI "int \fBnc_init\fP (int flags)"
.br
.RI "\fIInitialize libnetconf for system-wide usage\&. This initialization is shared across all the processes\&. \fP"
.ti -1c
.RI "int \fBnc_msgid_compare\fP (const \fBnc_msgid\fP id1, const \fBnc_msgid\fP id2)"
.br
.RI "\fICompare two message IDs if they are the same\&. \fP"
.ti -1c
.RI "char * \fBnc_time2datetime\fP (time_t time, const char *tz)"
.br
.RI "\fITransform given time_t (seconds since the epoch) into the RFC 3339 format accepted by NETCONF functions\&. \fP"
.ti -1c
.RI "void \fBnc_verb_error\fP (const char *format,\&.\&.\&.)"
.br
.RI "\fIFunction for logging error messages\&. \fP"
.ti -1c
.RI "void \fBnc_verb_verbose\fP (const char *format,\&.\&.\&.)"
.br
.RI "\fIFunction for logging verbose messages\&. \fP"
.ti -1c
.RI "void \fBnc_verb_warning\fP (const char *format,\&.\&.\&.)"
.br
.RI "\fIFunction for logging warning messages\&. \fP"
.ti -1c
.RI "void \fBnc_verbosity\fP (\fBNC_VERB_LEVEL\fP level)"
.br
.RI "\fISet libnetconf's verbosity level\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
libnetconf's miscellaneous functions\&. 


.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBNC_MSG_TYPE\fP"

.PP
Enumeration of NETCONF message types\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINC_MSG_UNKNOWN \fP\fP
error state 
.TP
\fB\fINC_MSG_WOULDBLOCK \fP\fP
waiting for another message timed out 
.TP
\fB\fINC_MSG_NONE \fP\fP
no message at input or message was processed internally 
.TP
\fB\fINC_MSG_HELLO \fP\fP
<hello> message 
.TP
\fB\fINC_MSG_RPC \fP\fP
<rpc> message 
.TP
\fB\fINC_MSG_REPLY \fP\fP
<rpc-reply> message 
.TP
\fB\fINC_MSG_NOTIFICATION \fP\fP
<notification> message 
.SS "enum \fBNC_VERB_LEVEL\fP"

.PP
Verbosity levels\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINC_VERB_ERROR \fP\fP
Print only error messages\&. 
.TP
\fB\fINC_VERB_WARNING \fP\fP
Print error and warning messages\&. 
.TP
\fB\fINC_VERB_VERBOSE \fP\fP
Besides errors and warnings, print some other verbose messages\&. 
.TP
\fB\fINC_VERB_DEBUG \fP\fP
Print all messages including some development debug messages\&. 
.SH "Function Documentation"
.PP 
.SS "void nc_callback_print (void(*)(\fBNC_VERB_LEVEL\fP level, const char *msg)func)"

.PP
Set a callback function for printing libnetconf's messages\&.
.PP
If the func parameter is NULL, the callback is set back to the default (no) function\&. 
.PP
\fBParameters:\fP
.RS 4
\fIfunc\fP Callback function to use\&. 
.RE
.PP

.SS "int nc_close (void)"

.PP
Release libnetconf resources\&. Init flag is used to determine if close should be applied as system-wide (NC_INIT_MULTILAYER) or not (NC_INIT_SINGLELAYER)\&. System-wide \fBnc_close()\fP closes all the shared structures if no other libnetconf participant is currently running\&. Local release of the calling instance from the shared structures is done in both cases\&. 
.PP
\fBReturns:\fP
.RS 4
-1 on error
.br
 0 on success
.br
 1 in case of system-wide when there is another participant using shared structures and system-wide close cannot be done\&. 
.RE
.PP

.SS "time_t nc_datetime2time (const char *datetime)"

.PP
Transform given string in RFC 3339 compliant format to the time_t (seconds since the epoch) accepted by most Linux functions\&. This is a reverse function to \fBnc_time2datetime()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIdatetime\fP Time structure returned e\&.g\&. by localtime()\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
time_t value of the given string\&. 
.RE
.PP

.SS "struct nc_err* nc_err_dup (const struct nc_err *error)"

.PP
Duplicate an error description structure\&. 
.PP
\fBParameters:\fP
.RS 4
\fIerror\fP Existing NETCONF error description structure to be duplicated\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Duplicated NETCONF error structure on success, NULL on an error\&. 
.RE
.PP

.SS "void nc_err_free (struct nc_err *err)"

.PP
Free NETCONF error structure\&. 
.PP
\fBParameters:\fP
.RS 4
\fIerr\fP NETCONF error structure to free\&. 
.RE
.PP

.SS "const char* nc_err_get (const struct nc_err *err, \fBNC_ERR_PARAM\fPparam)"

.PP
Get value of the specified parameter of the NETCONF error structure\&. 
.PP
\fBParameters:\fP
.RS 4
\fIerr\fP NETCONF error structure from which the value will be read\&. 
.br
\fIparam\fP NETCONF error structure's parameter to be returned\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Constant string value of the requested parameter, NULL if the specified parameter is not set\&. 
.RE
.PP

.SS "struct nc_err* nc_err_new (\fBNC_ERR\fPerror)"

.PP
Create a new error description structure\&. 
.PP
\fBParameters:\fP
.RS 4
\fIerror\fP Predefined NETCONF error (according to RFC 6241 Appendix A)\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Created NETCONF error structure on success, NULL on an error\&. 
.RE
.PP

.SS "int nc_err_set (struct nc_err *err, \fBNC_ERR_PARAM\fPparam, const char *value)"

.PP
Set selected parameter of the NETCONF error structure to the specified value\&. 
.PP
\fBParameters:\fP
.RS 4
\fIerr\fP NETCONF error structure to be modified\&. 
.br
\fIparam\fP NETCONF error structure's parameter to be modified\&. 
.br
\fIvalue\fP New value for the specified parameter\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success
.br
 non-zero on error 
.RE
.PP

.SS "void nc_hello_timeout (inttimeout)"

.PP
Set <hello> timeout - how long libnetconf will wait for the <hello> message from the other side\&. Default value is -1 (infinite timeout)\&. 
.PP
\fBParameters:\fP
.RS 4
\fItimeout\fP Timeout in milliseconds, -1 for infinite timeout, 0 for non-blocking\&. 
.RE
.PP

.SS "int nc_init (intflags)"

.PP
Initialize libnetconf for system-wide usage\&. This initialization is shared across all the processes\&. 
.PP
\fBParameters:\fP
.RS 4
\fIflags\fP ORed flags for libnetconf initialization\&. Must include \fINC_INIT_CLIENT\fP, \fINC_INIT_MULTILAYER\fP, or \fINC_INIT_SINGLELAYER\fP with other accepted values including:
.IP "\(bu" 2
\fINC_INIT_LIBSSH_PTHREAD\fP The application uses libssh and pthread threads
.IP "\(bu" 2
\fINC_INIT_ALL\fP Enable all available subsystems
.IP "\(bu" 2
\fINC_INIT_MONITORING\fP Enable ietf-netconf-monitoring module
.IP "\(bu" 2
\fINC_INIT_WD\fP Enable With-default capability
.IP "\(bu" 2
\fINC_INIT_NOTIF\fP Enable Notification subsystem
.IP "\(bu" 2
\fINC_INIT_NACM\fP Enable NETCONF Access Control subsystem
.PP
.RE
.PP
Clients call init just for libssh initialization, if it is used\&. The difference between the multi-layer and single-layer flag is strictly in the behaviour when cleaning shared library resources, either during \fBnc_close()\fP or if the calling process crashed before (equals did not call \fBnc_close()\fP)\&. On multi-layer crash/close, if it was/is the only running libnetconf application, full cleanup is performed, unlike single-layer crash, when this situation is reflected just in the return flag or single-layer close, when only the local resources are released\&.
.PP
\fBReturns:\fP
.RS 4
-1 on fatal error
.br
 0 on success with some possible flags:
.br
 NC_INITRET_NOTFIRST when someone else already called \fBnc_init()\fP since last system-wide \fBnc_close()\fP or system reboot\&.
.br
 NC_INITRET_RECOVERY when after last init and before this init this application crashed (based on same commands - executable binary names)\&. 
.RE
.PP

.SS "int nc_msgid_compare (const \fBnc_msgid\fPid1, const \fBnc_msgid\fPid2)"

.PP
Compare two message IDs if they are the same\&. 
.PP
\fBParameters:\fP
.RS 4
\fIid1\fP First message ID to compare\&. 
.br
\fIid2\fP Second message ID to compare\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 if both IDs are the same\&. 
.RE
.PP

.SS "char* nc_time2datetime (time_ttime, const char *tz)"

.PP
Transform given time_t (seconds since the epoch) into the RFC 3339 format accepted by NETCONF functions\&. This is a reverse function to \fBnc_datetime2time()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fItime\fP time_t type value returned e\&.g\&. by time()\&. 
.br
\fItz\fP timezone name for the result\&. See tzselect(1) for list of correct values\&. If not specified (NULL), the result is provided in UTC (Zulu)\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Printed string in a format compliant to RFC 3339\&. It is up to the caller to free the returned string\&. 
.RE
.PP

.SS "void nc_verb_error (const char *format, \&.\&.\&.)"

.PP
Function for logging error messages\&. 
.PP
\fBParameters:\fP
.RS 4
\fIformat\fP printf's format string 
.br
\fI\&.\&.\&.\fP list of arguments specified in format 
.RE
.PP

.SS "void nc_verb_verbose (const char *format, \&.\&.\&.)"

.PP
Function for logging verbose messages\&. 
.PP
\fBParameters:\fP
.RS 4
\fIformat\fP printf's format string 
.br
\fI\&.\&.\&.\fP list of arguments specified in format 
.RE
.PP

.SS "void nc_verb_warning (const char *format, \&.\&.\&.)"

.PP
Function for logging warning messages\&. 
.PP
\fBParameters:\fP
.RS 4
\fIformat\fP printf's format string 
.br
\fI\&.\&.\&.\fP list of arguments specified in format 
.RE
.PP

.SS "void nc_verbosity (\fBNC_VERB_LEVEL\fPlevel)"

.PP
Set libnetconf's verbosity level\&. 
.PP
\fBParameters:\fP
.RS 4
\fIlevel\fP Enabled verbosity level (includes all the levels with higher priority)\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libnetconf from the source code\&.
